#ifndef VXP_ERRORS_H
#define VXP_ERRORS_H

/** @file errors.h
* Declares functions that handle Flex, Bison, AST and memory allocation errors.
*
* @author Victor Petrov <victor_petrov@harvard.edu>
* @date   Feb 27, 2011
* @cond
*------------------------------------------------------------------------------
* LEGAL:
*------------------------------------------------------------------------------
*
* Copyright (c) 2011, The President and Fellows of Harvard College
* Copyright (c) 2011, The Neuroinformatics Research Group at Harvard University
* All rights reserved.
*
* License: New BSD License   <http://creativecommons.org/licenses/BSD/>
*-------------------------
* Redistribution and use in source and binary forms, with or without 
* modification, are permitted provided that the following conditions are met:
*
*	Redistributions of source code must retain the above copyright notice, 
*	this list of conditions and the following disclaimer.
*
*	Redistributions in binary form must reproduce the above copyright notice, 
*	this list of conditions and the following disclaimer in the documentation
*	and/or other materials provided with the distribution.
*
*	Neither the name of the Neuroinformatics Research Group at Harvard, nor 
*	the names of its contributors may be used to endorse or promote products 
*	derived from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 
* AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 
* ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 
* LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 
* CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
* SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 
* INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 
* CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 
* ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
* POSSIBILITY OF SUCH DAMAGE.
*------------------------------------------------------------------------------
* vim: ts=4
*------------------------------------------------------------------------------
* @endcond
*/

#ifdef PHPEXT
	#include "php.h"
#endif

#include "ast.h"            /* struct Node */

/** The types of errors available */
enum vxpErrors
{
	VXP_ERROR,                  /**< A generic error */
	VXP_ERROR_SYNTAX,           /**< A syntax error (Bison) */
	VXP_ERROR_MEMORY,           /**< A memory error (Bison) */
	VXP_ERROR_BAD_CHAR          /**< A bad character was encountered (Flex) */
};


/** Handles errors generated by Flex/Bison.
* In the PHP extension, this function will throw an XPathException.
* In the vxp utility, this function calls vxpExit().
* @note (PHP only) If Flex encounters an unexpected character, it will call
*       badcharerror() first, which will thrown an XPathException, 
*       but, badcharerror() does not cause vxp_parse() to terminate, and so 
*       Bison calls vxp_error() to complain about an unexpected end of input.
*       To solve this, YY_EXTRA_TYPE and vxp_get_extra() are used to avoid 
*       throwing a second XPathException.
*       When @c vxp_get_extra()->errorKind==VXP_ERROR_BAD_CHAR, vxp_error()
*       will silently return and it will @b not throw an XPathException.
* @param[in] yylloc_param Bison location
* @param[in] yyscanner    Flex internal data structure
* @param[in] root         A pointer to the root Node
* @param[in] mem          The MemBlockInfo struct for handling memory 
* @param[in] message      Bison / Flex error message
* @throw XPathException   (PHP only) XPathException::SYNTAX
* @throw XPathException   (PHP only) XPathException::MEMORY
* @return The return value should be ignored.
* @warning The declaration of vxp_error() must match what Bison generates
*          based on \%parse-param and \%lex-param
* @warning This function will either terminate the vxp program or, for PHP,
*          it will throw an XPathException.
*/
int vxp_error(YYLTYPE *yylloc_param, void* yyscanner, struct Node** root,
              struct MemBlockInfo* mem, const char* const message);

/** Handles memory allocation errors.
* In the PHP extension, this function calls php_error_docref().
* In the vxp utility, this function calls vxpExit().
* @param[in] bytes Number of bytes tried to allocate
* @param[in] func  Name of the function (@c __func__ )
* @param[in] file  Name of the file     (@c __FILE__ )
* @param[in] line  Line number          (@c __LINE__ )
* @param[in] mem   The MemBlockInfo struct reponsible for memory allocations 
* @warning This function terminates the vxp program or the PHP script.
*/
void memerror(  unsigned int bytes,
                const char* func,
                const char* file, 
                const int line,
				struct MemBlockInfo* mem);

/** Handles internal AST errors.
* In the PHP extension, this function throws XPathException.
* In the vxp utility, this function calls vxpExit().
* @see XPathException::ERROR
* @param[in] message The error message
* @param[in] node1   The first node, if available
* @param[in] node2   The second node, if available
* @param[in] mem   The MemBlockInfo struct reponsible for memory allocations 
* @warning This function terminates the vxp program or the PHP script.
* @throws XPathException (for PHP only) XPathException::ERROR
*/
void nodeerror( const char* const message, 
                const struct Node* node1, 
                const struct Node* node2,
				struct MemBlockInfo* mem);

/** Handles Flex error, when the XPath contains an invalid character.
* In the PHP extension, this methods throws XPathException.
* In the vxp utility, this function calls vxpExit().
* @see XPathException::BAD_CHAR
* @param[in] invalid   The invalid character
* @param[in] line      The line in the XPath string
* @param[in] col       The column in the XPath string
* @param[in] mem       The MemBlockInfo struct responsible for memory allocations
* @throws XPathException (for PHP only) XPathException::BAD_CHAR
*/
void badcharerror(char invalid, int line, int col, struct MemBlockInfo* mem);

#endif

